Skip to content

docs(readme): document clustering and add replication/HA roadmap - #185

Merged
kacy merged 1 commit into
mainfrom
docs/readme-cluster-replication-roadmap
Feb 19, 2026
Merged

docs(readme): document clustering and add replication/HA roadmap#185
kacy merged 1 commit into
mainfrom
docs/readme-cluster-replication-roadmap

Conversation

@kacy

@kacy kacy commented Feb 19, 2026

Copy link
Copy Markdown
Owner

summary

the readme's clustering section existed but didn't explain what the cluster actually does or show how to start one manually. this PR fills in the gaps and adds the replication/HA roadmap now that the cluster module is architecturally complete.

changes:

  • new one-line summary of how clustering works (16384 hash slots, SWIM gossip, Raft topology, MOVED/ASK)
  • manual 3-node quickstart alongside the make cluster shortcut, showing --cluster-enabled, --cluster-bootstrap, CLUSTER MEET, and slot assignment
  • full cluster command reference table (15 commands)
  • note that REPLICATE and FAILOVER are coming next — with a pointer to the status table
  • four new cluster config flags in the configuration table (--cluster-enabled, --cluster-bootstrap, --cluster-port-offset, --cluster-node-timeout)
  • architecture section now describes cluster mode alongside sharded and concurrent modes
  • status table updated: phase 5 stays 🚧 (CLI and observability done, clients not started), phase 6 added as 🔜 with a brief description of what remains (replication stream, role propagation, failover)
  • stats updated: 1,049 tests, ~22k LOC (~41k including tests/comments), 107 commands

what was tested

  • cargo build --workspace — clean build
  • cargo clippy --workspace -- -D warnings — zero warnings
  • cargo fmt --check — clean (one unrelated formatting fix in integration tests included)
  • read through the full clustering section for accuracy and flow

design considerations

the manual quickstart uses $(seq 0 5460 | tr '\n' ' ') for slot assignment. this is realistic for documentation — in practice make cluster handles it. the replication roadmap is kept brief in the README (one paragraph + status row) since the detailed design lives in the implementation plan.

- add cluster mode to features list
- expand clustering section: one-line summary, manual quickstart,
  full command table (INFO, NODES, SLOTS, KEYSLOT, MYID, MEET,
  ADDSLOTS, DELSLOTS, FORGET, SETSLOT, COUNTKEYSINSLOT, GETKEYSINSLOT,
  MIGRATE, RESTORE, ASKING), note on upcoming REPLICATE/FAILOVER
- add cluster config flags to configuration table
  (--cluster-enabled, --cluster-bootstrap, --cluster-port-offset,
  --cluster-node-timeout)
- describe cluster mode in architecture section alongside sharded
  and concurrent modes
- update status table: phase 5 stays in progress (clients not started),
  add phase 6 (replication/HA) as next, brief description of what remains
- update stats: 1,049 tests, ~22k LOC (~41k with tests/comments)
@kacy
kacy merged commit acb13d1 into main Feb 19, 2026
5 of 7 checks passed
@kacy
kacy deleted the docs/readme-cluster-replication-roadmap branch February 19, 2026 00:01
kacy added a commit that referenced this pull request Feb 19, 2026
- add cluster mode to features list
- expand clustering section: one-line summary, manual quickstart,
  full command table (INFO, NODES, SLOTS, KEYSLOT, MYID, MEET,
  ADDSLOTS, DELSLOTS, FORGET, SETSLOT, COUNTKEYSINSLOT, GETKEYSINSLOT,
  MIGRATE, RESTORE, ASKING), note on upcoming REPLICATE/FAILOVER
- add cluster config flags to configuration table
  (--cluster-enabled, --cluster-bootstrap, --cluster-port-offset,
  --cluster-node-timeout)
- describe cluster mode in architecture section alongside sharded
  and concurrent modes
- update status table: phase 5 stays in progress (clients not started),
  add phase 6 (replication/HA) as next, brief description of what remains
- update stats: 1,049 tests, ~22k LOC (~41k with tests/comments)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant